package cn.iocoder.yudao.module.system.service.studentdashboard;

import cn.iocoder.yudao.module.system.controller.admin.studentdashboard.vo.*;

import javax.validation.Valid;

/**
 * 学生看板 Service 接口
 *
 * @author 芋道源码
 */
public interface StudentDashboardService {

    /**
     * 获取学生看板数据
     *
     * @param reqVO 查询请求
     * @return 学生看板数据
     */
    StudentDashboardRespVO getStudentDashboard(@Valid StudentDashboardReqVO reqVO);

    /**
     * 获取学生排名信息
     *
     * @param reqVO 查询请求
     * @return 学生排名信息
     */
    StudentRankingRespVO getStudentRanking(@Valid StudentRankingReqVO reqVO);

    /**
     * 获取学生考试对比数据
     *
     * @param reqVO 查询请求
     * @return 考试对比数据
     */
    StudentExamComparisonRespVO getStudentExamComparison(@Valid StudentExamComparisonReqVO reqVO);

    /**
     * 获取学生在指定考试中的班级排名
     *
     * @param studentId 学生ID
     * @param examId 考试ID
     * @return 班级排名，如果未找到则返回null
     */
    Integer getStudentClassRank(Long studentId, Long examId);

    /**
     * 获取学生在指定考试中的年级排名
     *
     * @param studentId 学生ID
     * @param examId 考试ID
     * @return 年级排名，如果未找到则返回null
     */
    Integer getStudentGradeRank(Long studentId, Long examId);

    /**
     * 获取学生在指定考试和科目中的班级排名
     *
     * @param studentId 学生ID
     * @param examId 考试ID
     * @param subjectName 科目名称
     * @return 科目班级排名，如果未找到则返回null
     */
    Integer getStudentSubjectClassRank(Long studentId, Long examId, String subjectName);

    /**
     * 获取学生在指定考试和科目中的年级排名
     *
     * @param studentId 学生ID
     * @param examId 考试ID
     * @param subjectName 科目名称
     * @return 科目年级排名，如果未找到则返回null
     */
    Integer getStudentSubjectGradeRank(Long studentId, Long examId, String subjectName);

    /**
     * 获取学生的等效位次和等效分信息
     *
     * @param studentId 学生ID
     * @param examId 考试ID
     * @param controlLineId 特控线ID
     * @return 等效位次和等效分信息
     */
    StudentDashboardRespVO.EquivalentScoreRankInfo getStudentEquivalentScoreRank(Long studentId, Long examId, Long controlLineId);

    /**
     * 计算学生的等效位次和等效分
     *
     * @param studentId 学生ID
     * @param examId 考试ID
     * @param controlLineId 特控线ID
     * @return 计算结果
     */
    StudentDashboardRespVO.EquivalentScoreRankInfo calculateStudentEquivalentScoreRank(Long studentId, Long examId, Long controlLineId);

    /**
     * 获取学生的等效位次趋势分析
     *
     * @param studentId 学生ID
     * @param examId 考试ID
     * @param controlLineId 特控线ID
     * @return 等效位次趋势分析
     */
    StudentDashboardRespVO.EquivalentRankTrendInfo getEquivalentRankTrend(Long studentId, Long examId, Long controlLineId);

    /**
     * 根据考试ID自动获取特控线，获取学生的等效位次和等效分信息
     *
     * @param studentId 学生ID
     * @param examId 考试ID
     * @return 等效位次和等效分信息
     */
    StudentDashboardRespVO.EquivalentScoreRankInfo getStudentEquivalentScoreRankByExam(Long studentId, Long examId);

    /**
     * 根据考试ID自动获取特控线，计算学生的等效位次和等效分
     *
     * @param studentId 学生ID
     * @param examId 考试ID
     * @return 计算结果
     */
    StudentDashboardRespVO.EquivalentScoreRankInfo calculateStudentEquivalentScoreRankByExam(Long studentId, Long examId);

    /**
     * 根据考试ID自动获取特控线，获取学生的等效位次趋势分析
     *
     * @param studentId 学生ID
     * @param examId 考试ID
     * @return 等效位次趋势分析
     */
    StudentDashboardRespVO.EquivalentRankTrendInfo getEquivalentRankTrendByExam(Long studentId, Long examId);

}
